home *** CD-ROM | disk | FTP | other *** search
/ Freelog 22 / freelog 22.iso / Prog / Djgpp / GPC2952B.ZIP / info / gpc.i19 < prev    next >
Encoding:
GNU Info File  |  2001-02-09  |  49.1 KB  |  1,332 lines
  1. This is gpc.info, produced by makeinfo version 4.0 from gpc.texi.
  2.  
  3. INFO-DIR-SECTION GNU programming tools
  4. START-INFO-DIR-ENTRY
  5. * GPC: (gpc).                   The GNU Pascal Compiler.
  6. END-INFO-DIR-ENTRY
  7. INFO-DIR-SECTION Individual utilities
  8. START-INFO-DIR-ENTRY
  9. * GPC: (gpc)Invoking GPC.       The GNU Pascal Compiler.
  10. END-INFO-DIR-ENTRY
  11.  
  12.    This file documents the GNU Pascal Compiler.
  13.  
  14.    Copyright (C) 1988, 1996-2001 Free Software Foundation, Inc.
  15.  
  16.    Permission is granted to make and distribute verbatim copies of this
  17. manual provided the copyright notice and this permission notice are
  18. preserved on all copies.
  19.  
  20.    Permission is granted to copy and distribute modified versions of
  21. this manual under the conditions for verbatim copying, provided also
  22. that the sections entitled "GNU General Public License", "The GNU
  23. Project", "The GNU Manifesto" and "Funding for Free Software" are
  24. included exactly as in the original, and provided that the entire
  25. resulting derived work is distributed under the terms of a permission
  26. notice identical to this one.
  27.  
  28.    Permission is granted to copy and distribute translations of this
  29. manual into another language, under the above conditions for modified
  30. versions, except that the sections entitled "GNU General Public
  31. License", "The GNU Project", "The GNU Manifesto" and "Funding for Free
  32. Software" and this permission notice, may be included in translations
  33. approved by the Free Software Foundation instead of in the original
  34. English.
  35.  
  36. 
  37. File: gpc.info,  Node: Implemented Features,  Prev: Fixed Bugs,  Up: Done
  38.  
  39. Features that have been implemented
  40. -----------------------------------
  41.  
  42.    This section lists the new features implemented since 1st Nov 1997,
  43. together with the date (YYYYMMDD) on which they were implemented.
  44.  
  45.    After the release of GPC 2.1, this section will be cleared, and the
  46. features implemented after that release will either be listed in a new
  47. section here or directly in the "news".
  48.  
  49.    * 20010121: Trap: new procedure `TrapReset'
  50.  
  51.    * 20010110: `uses' and `import' may now occur multiple times in a
  52.      program, unit/module interface or unit/module implementation, even
  53.      between declarations
  54.  
  55.    * 20010108: parserdemo: added factorial support
  56.  
  57.    * 20010107: new functions `IsAlpha', `IsSpace'
  58.  
  59.    * 20001216: CRT: new functions `AltGrKey', `ExtraKey'
  60.  
  61.    * 20001215: new function `GetTempFileNameInDirectory'
  62.  
  63.    * 20001210: new function `FormatTime', new constant `InvalidYear'
  64.  
  65.    * 20001206: new constant `MaskNoStdDir'
  66.  
  67.    * 20001205: the constant `MonthLength' was replaced by a function of
  68.      the same name that handles leap years
  69.  
  70.    * 20001201: new constant `FileMode_Text_Reset_ReadWrite'
  71.  
  72.    * 20001115: `shl' and `shr' can also be used as procedures now
  73.  
  74.    * 20001112: new switches `-W[no-]object-directives'
  75.  
  76.    * 20001106: StringUtils: new routines `AppendStr', `StrCut',
  77.      `Char2Boolean', `StrSkipSpaces', `StrReadQuoted',
  78.      `StrReadDelimited', `StrReadWord', `StrReadConst', `StrReadComma',
  79.      `StrReadInt', `StrReadReal', `StrReadBoolean', `StrReadEnum'
  80.  
  81.    * 20001017: DisposePPStrings
  82.  
  83.    * 20001016: `GetIOErrorMessage' now returns a string rather than a
  84.      `CString'
  85.  
  86.    * 20001016: RegExType: changed the field `Error' from `CString' to
  87.      `PString'
  88.  
  89.    * 20001016: GlobBuffer: replaced fields `Count' and `Result' by
  90.      `Result' (`PPStrings')
  91.  
  92.    * 20001015: `GetOptErrorFlag' is now True by default
  93.  
  94.    * 20001014: StringUtils: new functions StrCount, StrReplace,
  95.      Char2Digit, QuoteString, UnQuoteString, ExpandTabs,
  96.      ExpandCEscapeSequences
  97.  
  98.    * 20001007: many new docdemo programs
  99.  
  100.    * 20001007: new options `-W[no-]underscore'
  101.  
  102.    * 20001003: many new docdemo programs
  103.  
  104.    * 20001001: many new `Reference' entries and new material in the
  105.      `Programming' chapter in the manual
  106.  
  107.    * 20000917: added the `Size' field of BindingType again
  108.  
  109.    * 20000910: don't add a newline on `Extend' to text files that were
  110.      bound as binary
  111.  
  112.    * 20000909: `GetOptLong' can now optionally derive the short options
  113.      from the `LongOptions' array
  114.  
  115.    * 20000909: `CStringCharPos', `CStringLastCharPos': renamed to
  116.      `CStringChPos' and `CStringLastChPos' to avoid confusion with
  117.      `CharPos' and `LastCharPos'
  118.  
  119.    * 20000902: CRT: new procedure CRTSetTerminal
  120.  
  121.    * 20000828: new procedure FileMove
  122.  
  123.    * 20000826: new constant DayOfWeekName
  124.  
  125.    * 20000825: integrated the FAQ into the GPC Manual
  126.  
  127.    * 20000820: new routines SystemInfo, FileLock, FileUnlock, Alarm
  128.  
  129.    * 20000819: StringUtils: new unit, implementing a string hash table
  130.      (further routines to be added)
  131.  
  132.    * 20000817: CRT: new routines CRTSavePreviousScreen,
  133.      CRTSavePreviousScreenWorks
  134.  
  135.    * 20000806: new function GetTerminalName
  136.  
  137.    * 20000803: new functions UserID, GroupID
  138.  
  139.    * 20000723: new parameter `AccessTime' to SetFileName
  140.  
  141.    * 20000716: renamed the file mode constants from `fmFOO' to `fm_FOO'
  142.  
  143.    * 20000716: new routines MemoryMap, MemoryUnMap
  144.  
  145.    * 20000626: the default make target for testing GPC is called
  146.      `pascal.check' (or `check-pascal') rather than `check-gpc' now;
  147.      the test must be run in the build directory (not the `p'
  148.      subdirectory) or in the `test' subdirectory of the source
  149.      directory now
  150.  
  151.    * 20000619: `--borland-pascal': ignore everything after `end.' (also
  152.      takes care of "^Z" characters at the end of Dos text files)
  153.  
  154.    * 20000613: Dos: special versions of GetCBreak and SetCBreak for
  155.      MS-Windows
  156.  
  157.    * 20000612: Dos: new procedures (not only on DJGPP) DosVersion,
  158.      SetDate, SetTime
  159.  
  160.    * 20000611: CRT: new procedures `SetScreenSize', `SetMonochrome';
  161.      renamed `IsMonoMode' to `IsMonochrome'
  162.  
  163.    * 20000610: each of the parameters `Dir', `Name' and `Ext' to
  164.      `FSplit' may now be null
  165.  
  166.    * 20000607: Single RTS command line options are now recognized with
  167.      `--gpc-rts=OPTION' as well, and this can be given multiple times
  168.  
  169.    * 20000607: new procedure ResetGetOpt
  170.  
  171.    * 20000606: CRT: new functions CtrlKey, AltKey; new constants
  172.      chCtrlA ... chCtrlZ, kbCtrlA ... kbCtrlZ
  173.  
  174.    * 20000605: new routines BlockSignal, SignalBlocked
  175.  
  176.    * 20000605: CRT with ncurses: changing the screen is now done
  177.      through a shell command definable in the environment variable
  178.      `RESIZETERM' (which defaults to `resize', `SVGATextMode' and
  179.      `setfont'); the variables `crt_setfont_command_80_25',
  180.      `crt_setfont_command_80_50', `crt_setfont_command_40_25' and
  181.      `crt_setfont_command_40_50' (Linux only) were removed
  182.  
  183.    * 20000604: Dos: new procedures (not only on DJGPP) GetCBreak,
  184.      SetCBreak, GetVerify, SetVerify
  185.  
  186.    * 20000604: new routines SetInputSignals, GetInputSignals
  187.  
  188.    * 20000531: new demo program `DynamicArrayDemo'
  189.  
  190.    * 20000530: integrated the interface of all units included with GPC
  191.      into the GPC Manual; formatted the interfaces, also of gpc.pas,
  192.      more nicely
  193.  
  194.    * 20000528: integrated the To-Do list and the list of new GPC
  195.      features into the GPC Manual
  196.  
  197.    * 20000528: include the demo programs printed in the GPC Manual
  198.      (currently 59, but expected to become more) into binary
  199.      distributions in a directory `docdemos'
  200.  
  201.    * 20000527: restructured the GPC Manual
  202.  
  203.    * 20000526: in the GPC Manual, the list of command-line options and
  204.      the list of keywords for the various dialects were updated, and
  205.      from now on, they are automatically kept up to date, directly from
  206.      the source
  207.  
  208.    * 20000526: changed the license of most units and the RTS from LGPL
  209.      + exception to GPL + exception
  210.  
  211.    * 20000525: ReverseBytes, ConvertFromLittleEndian,
  212.      ConvertFromBigEndian, ConvertToLittleEndian, ConvertToBigEndian:
  213.      new parameter `ElementSize'; new demo program `EndianDemo'
  214.  
  215.    * 20000523: derive the keyword list in the documentation directly
  216.      from the source
  217.  
  218.    * 20000521: WinCRT: new unit (identical to CRT)
  219.  
  220.    * 20000521: CRT: GetScreenSize renamed to ScreenSize (WinCRT
  221.      compatibility); added some missing WinCRT compatibility stuff
  222.  
  223.    * 20000519: new function GetMountPoint
  224.  
  225.    * 20000516: new field Device in BindingType
  226.  
  227.    * 20000516: BlockReadLittleEndian, BlockReadBigEndian,
  228.      BlockWriteLittleEndian, BlockWriteBigEndian: new parameter
  229.      `ElementSize'
  230.  
  231.    * 20000516: new procedures ReadStringLittleEndian,
  232.      ReadStringBigEndian, WriteStringLittleEndian, WriteStringBigEndian
  233.  
  234.    * 20000509: System: new functions Ofs, Seg, Ptr, CSeg, DSeg, SSeg,
  235.      SPtr and a number of variables (mostly useless and only for BP
  236.      compatibility)
  237.  
  238.    * 20000507: new procedure IOErrorFile
  239.  
  240.    * 20000505: `asmname' in variable and constant declarations must now
  241.      come after the type; furthermore, `asmname' doesn't imply
  242.      `external' anymore
  243.  
  244.    * 20000502: SeekEOF, SeekEOLn
  245.  
  246.    * 20000421: new function InstallSignalHandler
  247.  
  248.    * 20000418: recognize files with `.pp' or `.dpr' extension as Pascal
  249.      sources
  250.  
  251.    * 20000415: new switch `{$[no-]debug-statement[=foo]}' (call a
  252.      procedure automatically before each statement for debugging)
  253.  
  254.    * 20000415: RTS command line options are now recognized after
  255.      `--gpc-rts' instead of `-Grts'
  256.  
  257.    * 20000415: removed `__cstring__', `__void__'
  258.  
  259.    * 20000414: the RTS command line options are now also available as
  260.      long options; new RTS options `--version' (print RTS version and
  261.      exit), `--abort-on-error' (abort with SIGABRT on runtime error),
  262.      `--error-file', `--error-fd' (dump runtime error messages and
  263.      strack trace to given file name or FD)
  264.  
  265.    * 20000412: runtime errors are now printed with their address to
  266.      help debugging (using addr2line), and the address is stored in
  267.      ErrorAddr
  268.  
  269.    * 20000411: new functions ReturnAddress, FrameAddress
  270.  
  271.    * 20000411: local compiler directives and defines with `{$local}'
  272.      and `{$endlocal}' (fjf430*.pas)
  273.  
  274.    * 20000409: `{$ifopt}'
  275.  
  276.    * 20000409: case-[in]sensitve defines with {{$csdefine}} and
  277.      {{$cidefine}} (or `-csdefine' and `cidefine'); `{$define}' (but
  278.      not `--define') is now case-insensitive
  279.  
  280.    * 20000407: make `mod' with negative right operand work like in BP;
  281.      allow expressions like `-2 * +3'
  282.  
  283.    * 20000407: `make check' now runs the current test suite rather than
  284.      the (obsolete and removed) dejagnu tests; the test suite now
  285.      produces a summary output by default, `make pascal.check-long' (or
  286.      `check-pascal-long') produces the long output format as before
  287.  
  288.    * 20000407: new option `-W[no-]warnings' (enable/disable warnings)
  289.  
  290.    * 20000407: make single-letter compiler directives BP compatible
  291.      (`--borland-pascal': ignore `$F', `$O' etc., ignore numbers after
  292.      `$M'); new option `--[no-]stack-checking', also as compiler
  293.      directives `{$[no-]stack-checking}' or `{$S+}'/`{$S-}'; new option
  294.      `--[no-]typed-address', also as compiler directives
  295.      `{$[no-]typed-address}' or `{$T+}'/`{$T-}'; replace
  296.      `{$P+}'/`{$P-}' by `{$[no-]pedantic}' (or `--[no-]pedantic' on the
  297.      command line); ignore `{W+}'/`{W-}' in `--borland-pascal' mode
  298.  
  299.    * 20000406: CRT: new variable CRTAutoInitProc; new procedure
  300.      CRTNotInitialized
  301.  
  302.    * 20000405: new switches `--[no-]macros'
  303.  
  304.    * 20000402: new switches `-W[no-]field-name-problem'
  305.  
  306.    * 20000402: allow all `-Wfoo' options also as `{$W foo}' directives
  307.      (no more `{$Wfoo}' like in the last alpha release!)
  308.  
  309.    * 20000331: replace `--no-nested-comments' by `--mixed-comments'
  310.      (and vice versa); new options `--[no-]nested-comments',
  311.      `-W[no-]mixed-comments', `-W[no-]nested-comments' (mixcom*.pas,
  312.      nest*.pas); allow comments (but not compiler directives) within
  313.      compiler directives
  314.  
  315.    * 20000331: make C style char escapes the default for strings
  316.      enclosed in `""' (like `--char-escapes' used to do), and use `\"'
  317.      rather than `""' to get a verbatim `"' in them; remove the
  318.      `--[no-]char-escapes' switch and the `{$E[+-]}' compiler directive
  319.  
  320.    * 20000331: Delphi style `//' comments, new switch
  321.      `--[no-]delphi-comments' and compiler option
  322.      `{$[no-]delphi-comments}'
  323.  
  324.    * 20000327: new header gpc-in-c.h for inclusion of GPC code into C
  325.      programs; new demo program GPC_C_Pas to demonstrate this
  326.  
  327.    * 20000327: allow `^const' to create a pointer to a constant
  328.  
  329.    * 20000327: don't expand macros in `--borland-pascal' and `--delphi'
  330.  
  331.    * 20000327: Dos: added the unportable Dos-only routines under DJGPP
  332.      if `__BP_UNPORTABLE_ROUTINES__' is defined
  333.  
  334.    * 20000326: removed `__asmname__', `__const__', `__external__',
  335.      `__inline__', `__static__', `__volatile__', `__byte__',
  336.      `__short__', `__long__', `__longlong__', `__unsigned__'
  337.  
  338.    * 20000322: cleaned up the lexer; removed some fossils, e.g.
  339.      `--c-numbers'
  340.  
  341.    * 20000306: file sizes can now be bigger than `Integer' (e.g. 64 bit
  342.      files on 32 bit machines) if supported by the OS via lseek64() or
  343.      llseek() (e.g. Linux, Solaris, IRIX)
  344.  
  345.    * 20000221: new types ByteBool, ShortBool, WordBool, MedBool,
  346.      LongBool, LongestBool, Boolean(n) (fjf395.pas)
  347.  
  348.    * 20000219: build in `Include', `Exclude'
  349.  
  350.    * 20000213: make `nil' also a value of any procedural/functional
  351.      type (fjf258[a-e].pas)
  352.  
  353.    * 20000211: new functions `PathExists', `DataDirectoryName', new
  354.      parameter `Prefix' to `ConfigFileName'
  355.  
  356.    * 20000211: new fields SymLink, TextBinary in BindingType; new
  357.      procedure AssignBinary; removed variable TextFilesBinary
  358.  
  359.    * 20000202: new options `--[no-]progress-messages',
  360.      `--[no-]progress-bar'
  361.  
  362.    * 20000202: ignore `{$L+}'/`{$L-}' directives (for BP compatibility)
  363.  
  364.    * 20000131: new unit MD5; new demo program MD5Demo
  365.  
  366.    * 20000124: new unit FileUtils; new demo program FindFilesDemo
  367.  
  368.    * 20000111: changed the internal file handling from using `FILE *'
  369.      to integer file handles, to make it more efficient and get rid of
  370.      some problems; replaced the `CFile' field in `BindingType' by a
  371.      `Handle' field; replaced the `AssignCFile' procedure by an
  372.      `AssignHandle' procedure; removed the `GetFile' function (note
  373.      `FileHandle')
  374.  
  375.    * 20000111: new function Integer2String
  376.  
  377.    * 20000106: new functions IsPrintable, CharSet2RegEx
  378.  
  379.    * 19991217: System: new functions RealToBPReal, BPRealToReal
  380.  
  381.    * 19991217: new functions IsInfinity, IsNotANumber, SplitReal
  382.  
  383.    * 19991124: new demo program ProcVarDemo
  384.  
  385.    * 19991117: new function `LongReal2Str' to work-around the `Work
  386.      (Real)' problem under IRIX
  387.  
  388.    * 19991110: CRT: DJGPP: added support for 40 column modes (requires
  389.      updated PDCurses library)
  390.  
  391.    * 19991104: new demo program FExpandDemo
  392.  
  393.    * 19991103: CRT: changed the define to get an X11 version from
  394.      XCURSES to X11
  395.  
  396.    * 19991102: added `Special' field to BindingType
  397.  
  398.    * 19991101: new function GetShellPath
  399.  
  400.    * 19991101: new option `--[no-]transparent-file-names' to derive the
  401.      external file names from the file variable names
  402.      <199909010105.VAA23844@kaylor.ncifcrf.gov> (fjf394.pas)
  403.  
  404.    * 19991025: CRT: new procedures SimulateBlockCursor,
  405.      SimulateBlockCursorOff
  406.  
  407.    * 19991023: CRT: don't initialize curses at the beginning of the
  408.      program, but initialize it automatically when the first CRT
  409.      routine is called (for BP compatiblity); new procedure CRTInit to
  410.      explicitly initialize CRT which also sets some defaults (PCCharSet
  411.      and update level) to more natural (and less BP compatible) values
  412.  
  413.    * 19991023: CRT: allow any of the parameters to GetWindow to be null
  414.  
  415.    * 19991014: new procedure ReAlloc; previous ReAlloc function (libc)
  416.      renamed to CReAlloc; new variable ReAllocPtr
  417.  
  418.    * 19991014: new functions GetPasswordEntryByName,
  419.      GetPasswordEntryByUID, GetPasswordEntries; make ExpandEnvironment
  420.      recognize `~user'
  421.  
  422.    * 19991006: RegEx: support for converting subexpression references
  423.      to upper/lower case while replacing them with `\u7'/`\l7'
  424.  
  425.    * 19990924: new functions MemCompCase, StrEqualCase, PosCase,
  426.      LastPosCase, PosFromCase, LastPosTillCase, IsPrefixCase,
  427.      IsSuffixCase, ExecuteNoTerminal
  428.  
  429.    * 19990922: System: new procedure SetTextBuf for BP compatibility
  430.  
  431.    * 19990905: before building the RTS, make sure that the compiler
  432.      version used is current, to prevent strange bugs when building
  433.      with an older version <17698.990820@mg.dp.ua>
  434.  
  435.    * 19990805: new procedure SeedRandom; new variable SeedRandomPtr;
  436.      automatically initialize the random number generator like
  437.      Randomize does at the first call to Random unless SeedRandom was
  438.      called before (only for the default RNG; not the BP compatible one
  439.      in the System unit)
  440.  
  441.    * 19990802: new procedure RestoreTerminalClearCRT
  442.  
  443.    * 19990801: CRT: added support for panels (overlapping windows); new
  444.      routines GetActivePanel, PanelNew, PanelDelete,
  445.      PanelBindToBackground, PanelIsBoundToBackground, PanelActivate,
  446.      PanelHide, PanelShow, PanelHidden, PanelTop, PanelBottom,
  447.      PanelMoveAbove, PanelMoveBelow, PanelAbove, PanelBelow,
  448.      IgnoreCursor
  449.  
  450.    * 19990728: new demo program ArraySliceDemo
  451.  
  452.    * 19990727: CRT: replaced the variables PCCharSet and
  453.      UseControlChars by routines SetPCCharSet, GetPCCharSet,
  454.      SetControlChars, GetControlChars
  455.  
  456.    * 19990727: GMP: new procedures mpf_exp, mpf_ln, mpf_pow,
  457.      mpf_arctan, mpf_pi
  458.  
  459.    * 19990726: implemented environment variable management in Pascal,
  460.      so that it's independent of libc differences (e.g. the presence or
  461.      not of `environ'); new routines UnSetEnv, GetCEnvironment; removed
  462.      PutEnv and CSystem functions (obsoleted by SetEnv and Execute);
  463.      turned the Environment variable into a schema which contains the
  464.      environment variables as CStrings; allow empty and case-sensitive
  465.      environment variables within GPC programs even under Dos
  466.  
  467.    * 19990723: make `{$gnu-pascal}' completely equivalent to
  468.      `--gnu-pascal'; add `{$gnu-pascal}' to all included units so they
  469.      can also be compiled with `--automake' when `--foo-pascal' options
  470.      are given (dialec[1-6].pas)
  471.  
  472.    * 19990723: new options `-W[no-]typed-const' and `-W[no-]near-far'
  473.  
  474.    * 19990720: new functions SetTerminalProcessGroup,
  475.      GetTerminalProcessGroup
  476.  
  477.    * 19990719: new demo program RealPower
  478.  
  479.    * 19990709: new constants for signals; new routines Kill, WaitPID,
  480.      SetProcessGroup (formerly in the Pipe unit)
  481.  
  482.    * 19990622: new function FileHandle; un-built-in GetFile - it is now
  483.      in the GPC unit, but obsolete
  484.  
  485.    * 19990622: new routines AllocateBigMem, DisposeBigMem,
  486.      MoveToBigMem, MoveFromBigMem, MapBigMem for uniform access to big
  487.      memory blocks for GPC and BP; new demo program BigMemDemo
  488.  
  489.    * 19990617: integrated the PExecute unit into the RTS
  490.  
  491.    * 19990612: `register' directive
  492.  
  493.    * 19990609: integrated the GetOpt unit into the RTS (because the RTS
  494.      uses it, anyway); removed the Internal unit from the installation
  495.      (because using it from programs is really not recommendable)
  496.  
  497.    * 19990603: new procedure SetEnv (makes obsolete libc's PutEnv)
  498.  
  499.    * 19990601: included a `GPC' unit for BP to provide some GPC
  500.      compatibility to BP programs
  501.  
  502.    * 19990527: new demo program TrapDemo
  503.  
  504.    * 19990527: new units HeapMon, Trap
  505.  
  506.    * 19990527: new function ReleaseCount
  507.  
  508.    * 19990526: new routines RegisterRestoreTerminal,
  509.      UnregisterRestoreTerminal, RestoreTerminal
  510.  
  511.    * 19990502: new routine SetProcessGroup
  512.  
  513.    * 19990424: new function RegExPosFrom
  514.  
  515.    * 19990403: new constant FileNamesCaseSensitive, new function
  516.      FileNameLoCase
  517.  
  518.    * 19990327: added 20 demo programs
  519.  
  520.    * 19990325: new function GetMicroSecondTime
  521.  
  522.    * 19990324: renamed the CString routines in the RTS so they get a
  523.      `CString' prefix, moved the BP compatibility identifiers for the
  524.      same routines into the `Strings' unit
  525.  
  526.    * 19990308: `--no-default-paths'
  527.  
  528.    * 19990307: new functions IOSelect, IOSelectRead
  529.  
  530.    * 19990225: `--no-{unit,object}-path'
  531.  
  532.    * 19990225: `--[no-]io-checking' and `{$[no-]io-checking}' as
  533.      synonyms for `{$I+-}'
  534.  
  535.    * 19990219: recognize (but currently ignore)
  536.      published/public/protected/private
  537.  
  538.    * 19990218: renamed DataReady to CanRead
  539.  
  540.    * 19990213: change warnings of the form `Foo-Pascal does not have
  541.      foobars' into `foobars are {GPC-specific|a GPC extension}' and add
  542.      spaces before all but the first line of multi-line messages
  543.  
  544.    * 19990211: new procedures Sleep, SleepMicroSeconds, GetCPUTime
  545.  
  546.    * 19990211: CRT: new procedures CRTUpdate, CRTRedraw, SetScroll,
  547.      CRTSetCursesMode
  548.  
  549.    * 19990209: renamed the __BP_INTEGERS__ (System unit) and
  550.      _Borland_16_Bit_ (Dos and WinDos units) defines to
  551.      __BP_TYPE_SIZES__
  552.  
  553.    * 19990209: Pipe: new parameter `Process' to Pipe; new functions
  554.      WaitPipeProcess, StrSignal, Kill, WaitPID; new constants (actually
  555.      variables) for the signals
  556.  
  557.    * 19990205: new routines HasWildCardsOrBraces, BraceExpand,
  558.      MultiFileNameMatch, GlobOn, MultiGlob, MultiGlobOn, QuoteFileName,
  559.      UnQuoteFileName, FExpandQuoted, ForceAddDirSeparator,
  560.      FindNonQuotedChar, FindNonQuotedStr, NameExtFromPath; new
  561.      parameter `Quoted' to RelativePath
  562.  
  563.    * 19990202: new declarations DirRoot, QuotingCharacter, EnvVarChars,
  564.      EnvVarCharsFirst, WildCardChars, FileNameSpecialChars,
  565.      ShellExecCommand
  566.  
  567.    * 19990127: new functions IsUpCase, IsLoCase, IsAlphaNum,
  568.      IsAlphaNumUnderscore
  569.  
  570.    * 19990127: CRT: catch some signals and return pseudo function keys
  571.      for them if CheckBreak is False
  572.  
  573.    * 19990125: added `User', `Group', `Mode' and `INode' fields to
  574.      BindingType; new procedure ChMod
  575.  
  576.    * 19990125: CRT: react to screen size changes by external events and
  577.      return a pseudo function key
  578.  
  579.    * 19990115: built in `null' (= `nil^')
  580.  
  581.    * 19990115: Pipe unit (also for Dos!)
  582.  
  583.    * 19990115: new function DataReady to check if data can be read from
  584.      a file without blocking
  585.  
  586.    * 19990110: integrated the `PExecute' unit into GPC
  587.  
  588.    * 19990102: pass all given options to automake compilations too
  589.      (without having to repeat them with `--automake="foo"'), remove
  590.      `--automake="foo"'
  591.  
  592.    * 19990101: `--[no-]autolink' (default is autolink)
  593.  
  594.    * 19981228: `--[no-]executable-path',
  595.      `--[no-]unit-destination-path', `--[no-]object-destination-path'
  596.  
  597.    * 19981222: implemented buffering to speed up reading from files
  598.  
  599.    * 19981213: integrated the following units into GPC: `GetOpt',
  600.      `RegEx', `GMP', `Ports'
  601.  
  602.    * 19981212: new string routines: SetString, StringOfChar (Delphi
  603.      compatibility)
  604.  
  605.    * 19981212: integrated the `DosUnix' unit into GPC
  606.  
  607.    * 19981210: integrated the `GPCUtil' unit into GPC
  608.  
  609.    * 19981208: integrated the following units into GPC: `System',
  610.      `Turbo3'
  611.  
  612.    * 19981208: remove {$W-} as much as possible in the units
  613.  
  614.    * 19981208: built in Addr, Assigned
  615.  
  616.    * 19981207: integrated the following units into GPC: `CRT', `Dos',
  617.      `Overlay', `Printer', `Strings', `WinDos'
  618.  
  619.    * 19981206: `--unit-path' (upath.pas), `--object-path' (opath.pas);
  620.      don't allow them in a source file
  621.  
  622.    * 19981206: allow `Copy' with 2 arguments (fjf40e.pas)
  623.  
  624.    * 19981205: `FileName' function with a Pascal string return value
  625.  
  626.    * 19981205: interpret `{$L foo}' as `-lfoo'; accept files with `.so'
  627.      extension in `{$L}'
  628.  
  629.    * 19981203: pre-define `__OS_DOS__' on Dos-like systems
  630.  
  631.    * 19981202: `--uses=foo(bar.pas),bar,baz(../baz.pas)' (fjf101b.pas)
  632.  
  633.    * 19981202: make `=' and so on for strings work as exact comparisons
  634.      (`--borland-pascal'; `--[no-]exact-compare-strings')
  635.      (fjf38{,[a-f]}.pas)
  636.  
  637.    * 19981201: pre-define __BORLAND_PASCAL__ etc. depending on the
  638.      dialect options and __GNU_PASCAL__ if no dialect option was given
  639.      (dialdef{,[1-6]}.pas)
  640.  
  641.    * 19981108: new time routines UnixTimeToTimeStamp and
  642.      TimeStampToUnixTime
  643.  
  644.    * 19981108: added `AccessTime', `ModificationTime' and `ChangeTime'
  645.      fields to BindingType
  646.  
  647.    * 19981021: added a `Force' field to BindingType
  648.  
  649.    * 19980921: procedures to convert the endianness of single variables
  650.      (ReverseBytes, Convert{From,To}{Little,Big}Endian) and to do this
  651.      while reading/writing them from/to untyped files
  652.      (Block{Read,Write}{Little,Big}Endian)
  653.  
  654.    * 19980919: MaxLongInt
  655.  
  656.    * 19980918: a number of new CString routines, including almost all
  657.      (that weren't already there) of BP's strings unit
  658.  
  659.    * 19980918: WinDos: portable BP compatible unit with most of the
  660.      routines (those that can possibly be implemented in a portable way)
  661.  
  662.    * 19980917: CRT: some win (TP 5), wincrt and tpcrt compatibility
  663.      routines and some extensions added
  664.  
  665.    * 19980915: Internal: unit, with the internal RTS declarations from
  666.      gpc.pas moved into it
  667.  
  668.    * 19980914: System: remove built-in procedures UpCase, LoCase,
  669.      ChDir, MkDir, RmDir, FileSize, AddNullTerminator, InOutRes,
  670.      IOResult, FileMode
  671.  
  672.    * 19980914: System: GetDir, Lo, Hi, Swap, MemAvail, MaxAvail,
  673.      HeapError, HeapErrorNilReturn
  674.  
  675.    * 19980912: declared CGetMem, CFreeMem, ReAlloc
  676.  
  677.    * 19980909: build in GetMemPtr, FreeMemPtr
  678.  
  679.    * 19980830: allow `RunError' without arguments (error code -1)
  680.  
  681.    * 19980830: `--no-automake', `--no-autobuild', `--no-autolink' (each
  682.      of them disables all of `--autolink', `--automake' and
  683.      `--autobuild')
  684.  
  685.    * 19980822: internally remove the `type' parameter to _p_bind()
  686.  
  687.    * 19980818: build in GPC_StatFS
  688.  
  689.    * 19980724: procedures UpCaseString, LoCaseString, functions
  690.      UpCaseStr, LoCaseStr
  691.  
  692.    * 19980722: longest{int,real}-field-width (fieldw.pas)
  693.  
  694.    * 19980722: allow collecting options in several `--automake' oder
  695.      `--autobuild' options
  696.  
  697.    * 19980719: build in ExitCode, ErrorAddr
  698.  
  699.    * 19980719: Dos: portable BP compatible unit with most of the
  700.      routines (those that can possibly be implemented in a portable way)
  701.  
  702.    * 19980717: added a `DayOfWeek' field to TimeStamp and a DayOfWeek
  703.      function
  704.  
  705.    * 19980715: define __GPC_RELEASE__
  706.  
  707.    * 19980702: new CString functions: StrLen, StrEnd, StrScan,
  708.      StrRScan, StrDup, StrCmp, StrCaseCmp
  709.  
  710.    * 19980701: new file name declarations and routines: PathSeparator,
  711.      DirSeparator, DirSeparators, ExtSeparator, DirSelf, DirParent,
  712.      NullDevice, TTYDevice, ConsoleDevice, GetCurrentDirectory,
  713.      GetTempDirectory, GetTempFileName, GetTempFileName_CString,
  714.      Slash2OSDirSeparator, OSDirSeparator2Slash,
  715.      Slash2OSDirSeparator_CString, OSDirSeparator2Slash_CString,
  716.      FileExists, DirectoryExists, FSearch, FSearch_Executable,
  717.      Expand_Environment, FExpand, FSplit, DirFromPath, NameFromPath,
  718.      ExtFromPath, OpenDir, ReadDir, CloseDir
  719.  
  720.    * 19980629: runtime I/O error handling with {$I+-}
  721.  
  722.    * 19980629: build in NewCString, StrPCopy, CString2String
  723.      (fjf156.pas); String2CString
  724.  
  725.    * 19980629: build in UpCase, LoCase (locale-dependent, except in
  726.      `--borland-pascal', there only 7 bit ASCII)
  727.      (fjf165a.pas,fjf165b.pas)
  728.  
  729.    * 19980629: build in High, Low (for ordinal types and arrays)
  730.  
  731.    * 19980629: build in Random (for LongestCard and LongestReal),
  732.      Randomize
  733.  
  734.    * 19980629: build in SizeType, PtrDiffType
  735.  
  736.    * 19980629: build in Pi
  737.      <Pine.SGI.3.96.980318113542.2662B-100000@pugh.bip.bham.ac.uk>
  738.  
  739.    * 19980629: build in Erase, Rename, ChDir, MkDir, RmDir, FileMode,
  740.      Flush
  741.  
  742.    * 19980628: internally remove the unused second parameter of
  743.      Dispose/FreeMem
  744.  
  745.    * 19980626: allow mixing of New/GetMem/Dispose/FreeMem with
  746.      malloc()/free() and with Mark/Release (except free() with Release
  747.      in some cases)
  748.  
  749.    * 19980623: Turbo3 unit
  750.  
  751.    * 19980619: Printer: portable (piping to lpr under Un*x)
  752.  
  753.    * 19980613: `--gnu-pascal'
  754.  
  755.    * 19980611: CRT: portable ncurses-based unit
  756.  
  757.    * 19980604: print error messsages in the form: `a.out: [internal
  758.      error:] unknown code in `Write' (error #904)'
  759.  
  760.    * 19980531: when opening a file with a file name, do a binding
  761.      actually (fjf169.pas)
  762.  
  763.    * 19980523: added a `MicroSecond' field to TimeStamp
  764.  
  765.    * 19980520: printer unit for Dos
  766.  
  767.    * 19980520: `--uses="foo"' (fjf101.pas,fjf101a.pas)
  768.  
  769.    * 19980511: build in FilePos, FileSize, Truncate, Append
  770.  
  771.    * 19980511: build in RunError
  772.  
  773.    * 19980405: accept (but currently ignore) {$ifopt}
  774.  
  775.    * 19980405: When passing a long string value to a PChar parameter,
  776.      automatically add a #0 terminator
  777.  
  778.    * 19980405: allow `type y(b:integer)=array[1..b] of integer; x=y;'
  779.      (fjf115.pas)
  780.  
  781.    * 19980405: Fail (FreeMem, when constructor called by New)
  782.  
  783.    * 19980405: rename AssignLength and AssignType to SetLength and
  784.      SetType, resp., for Delphi compatibility
  785.  
  786.    * 19980405: warn about absolute declarations and type casts that can
  787.      cause alignment problems
  788.  
  789.    * 19980405: `--autobuild'
  790.  
  791.    * 19980129: predefine symbols for endianness
  792.  
  793.    * 19980114: recognize `--[no-]truncate-strings' in WriteStr
  794.      (fjf59.pas,truncstr.pas)
  795.  
  796.    * 19980114: build in untyped files and BlockRead, BlockWrite
  797.      (blockop.pas)
  798.  
  799.    * 19971230: build in Int, Frac (fjf129.pas)
  800.  
  801.    * 19971215: build in PtrInt, PtrCard, PtrWord
  802.  
  803.    * 19971130: allow opening files to `''' or `'-'' for stdin/stdout
  804.  
  805.    * 19971121: different versions of math functions for LongReal
  806.  
  807.    * 19971121: allow `with' for schema types
  808.      <199710152102.XAA04800@helena.mi.uni-erlangen.de> (fjf70.pas)
  809.  
  810.    * 19971121: allow `(var) := expr' (fjf100.pas)
  811.  
  812.    * 19971112: build in ParamCount, ParamStr (params.pas)
  813.  
  814.    * 19971112: initialize arrays of text in a loop rather than
  815.      individually (fh19971016) (fjf64.pas)
  816.  
  817.    * 19971112: build in Seek
  818.  
  819.    * 19971112: build in FillChar, Move (moving whole words), MoveLeft,
  820.      MoveRight (moving single bytes) (moves.pas)
  821.  
  822.    * 19971106: build in Delete (fjf62.pas) (fh19971008), Pos
  823.      (delinspos.pas), Copy
  824.  
  825.    * 19971106: AssignLength (alength.pas)
  826.  
  827.    * 19971101: make the char array in a String `[1..Capacity+1]' so
  828.      that there's always space for a #0 terminator
  829.  
  830.    * 19971101: build in Str and Val; Str in `--borland-pascal': only
  831.      one argument
  832.  
  833.    * 19971101: build in StdErr
  834.  
  835.    * 19971101: optimize `in' with set constructors
  836.  
  837.    * 19971101: build in Insert (fjf61.pas)
  838.  
  839. 
  840. File: gpc.info,  Node: Internals,  Next: Contributors,  Prev: To Do,  Up: Top
  841.  
  842. The GPC Source Reference
  843. ************************
  844.  
  845.      "The Source will be with you. Always."
  846.  
  847.    This chapter describes internals of GPC. It is meant for GPC
  848. developers and those who want to become devlopers, or just want to know
  849. more about how the compiler works. It does not contain information
  850. needed when using GPC to compile programs.
  851.  
  852.    This chapter tells you how to look up additional information about
  853. the GNU Pascal compiler from its source code.
  854.  
  855.    *Note:* If you intend to modify GPC's source, please check the top
  856. of each file you're going to modify. A number of files are generated
  857. automatically by various tools. The top of these files will tell you by
  858. which tool and from what file they were generated.  Modifying a
  859. generated file is pointless, since it will be overwritten the next time
  860. the tool is run. Instead, modify the original source (which will often
  861. be easier, anyway, e.g. a bison input file vs. the generated C code).
  862. This also holds for various documentation files.
  863.  
  864.    Proprietary compilers often come with a lot of technical information
  865. about the internals of the compiler. This is necessary because their
  866. vendors want to avoid to distribute the source of the compiler - which
  867. is always the most definitive source of this technical information.
  868.  
  869.    With GNU compilers, on the other hand, you are free to get the
  870. source code, look how your compiler works internally, customize it for
  871. your own needs, and to re-distribute it in modified or unmodified form.
  872. You may even take money for this redistribution.  (For details, see the
  873. GNU General Public License, *Note Copying::.)
  874.  
  875.    The following subsections are your guide to the GNU Pascal source
  876. code. If you have further questions, be welcome to ask them at the GNU
  877. Pascal mailing list (see *Note Support::).
  878.  
  879.    All file paths mentioned in this chapter are relative to the GNU
  880. Pascal source directory, usually a subdirectory `p' of the GCC source.
  881.  
  882. * Menu:
  883.  
  884. * Lexical analyzer::     `gpc-lex.c' -- How GPC reads your source.
  885. * Language definition::  `parse.y' -- ``Syntax diagrams'' as ``Bison'' source.
  886. * Tree nodes::           `../tree.*' -- How GPC stores your program internally.
  887. * Parameter passing::    `gpc-typeck.c' -- How GPC passes parameters.
  888. * GPI files::            `module.c' -- How GPC's precompiled Module/Unit interfaces work.
  889. * AutoMake::             `module.c' -- How GPC automatically ``makes'' a large project.
  890. * File Layout::          Files that make up GPC; Integrating GNU Pascal in GCC
  891.  
  892.    (Under construction.)
  893.  
  894.    For more information, see chapters "Portability" through "Fragments"
  895. in *Note the GCC documentation: (gcc)Top.
  896.  
  897. 
  898. File: gpc.info,  Node: Lexical analyzer,  Next: Language definition,  Up: Internals
  899.  
  900. GPC's Lexical Analyzer
  901. ======================
  902.  
  903.    The source file `gpc-lex.c' contains the so-called _lexical
  904. analyzer_ of the GNU Pascal compiler.  (For those of you who know
  905. `flex':  This file was _not_ created using `flex' but is maintained
  906. manually.)  This very-first stage of the compiler (after the
  907. preprocessor which is a separate executable) is responsible for reading
  908. what you have written and dividing it into _tokens_, the "atoms" of
  909. each computer language.  The source `gpc-lex.c' essentially contains
  910. one large function, `yylex()'.
  911.  
  912.    Here is, for example, where the real number `3.14' and the subrange
  913. `3..14' are distinguished, and where Borland-style character constants
  914. like `#13' and `^M' are recognized.  This is not always a trivial task,
  915. for example look at the following type declaration:
  916.  
  917.      type
  918.        X = ^Y;
  919.        Y = packed array [^A .. ^B] of Char;
  920.        Z = ^A .. ^Z;
  921.  
  922.    If you wish to know how GPC distinguishes the pointer forward
  923. declaration `^Y' and the subrange `^A..^Z', see `gpc-lex.c', function
  924. `yylex()', `case '^':' in the big `switch' statement.
  925.  
  926.    There are several situation where GPC's lexical analzyer becomes
  927. context-sensitive.  One is described above, another example is the token
  928. `protected', a reserved word in ISO-10206 Extended Pascal, but an
  929. ordinary identifier in ISO-7185 Standard Pascal.  It appears in
  930. parameter lists
  931.  
  932.      procedure foo (protected bar: Integer);
  933.  
  934.    and says that the parameter `bar' must not be changed inside the
  935. body of the procedure.
  936.  
  937.    OTOH, if you write a valid ISO-7185 Standard Pascal program, you can
  938. declare a parameter `protected':
  939.  
  940.      procedure foo (protected, bar: Integer);
  941.  
  942.    Here both standards contradict each other.  GPC solves this problem
  943. by checking explicitly for "protected" in the lexical analyzer:  If a
  944. comma or a colon follows, this is an ordinary identifier, otherwise
  945. it's a reserved word.  Having this, GPC even understands
  946.  
  947.      procedure foo (protected protected: Integer);
  948.  
  949.    without losing the special meaning of `protected' as a reserved word.
  950.  
  951.    The responsible code is in `gpc-lex.c' - look out for `PROTECTED'.
  952.  
  953.    If you ever encouter a bug with the lexical analyzer - now you know
  954. where to hunt for it.
  955.  
  956. 
  957. File: gpc.info,  Node: Language definition,  Next: Tree nodes,  Prev: Lexical analyzer,  Up: Internals
  958.  
  959. Language Definition: GPC's Parser
  960. =================================
  961.  
  962.    The file `parse.y' contains the "bison" source code of GNU Pascal's
  963. parser.  This stage of the compilation analyzes and checks the syntax of
  964. your Pascal program, and it generates an intermediate,
  965. language-independent code which is then passed to the GNU back-end.
  966.  
  967.    The _bison_ language essentially is a machine-readable form of the
  968. Backus-Naur Form, the symbolic notation of grammars of computer
  969. languages.  "Syntax diagrams" are a graphical variant of the
  970. Backus-Naur Form.
  971.  
  972.    For details about the "bison" language, see *Note the Bison
  973. documentation: (bison).  A short overview how to pick up some
  974. information you might need for programming follows.
  975.  
  976.    Suppose you have forgotten how a variable is declared in Pascal.
  977. After some searching in `parse.y' you have found the following:
  978.  
  979.      /* variable declaration part */
  980.      
  981.      variable_declaration_part:
  982.          LEX_VAR variable_declaration_list semi
  983.        | LEX_VAR semi
  984.            { error ("missing variable declaration"); }
  985.        ;
  986.      
  987.      variable_declaration_list:
  988.          variable_declaration
  989.        | variable_declaration_list semi variable_declaration
  990.            { yyerrok; }
  991.        | error
  992.        | variable_declaration_list error variable_declaration
  993.            {
  994.              error ("missing semicolon");
  995.              yyerrok;
  996.            }
  997.        | variable_declaration_list semi error
  998.        ;
  999.  
  1000.    Translated into English, this means: "The variable declaration part
  1001. consists of the reserved word (lexical token) `var' followed by a
  1002. `variable declaration list' and a semicolon.  A semicolon immediately
  1003. following `var' is an error.  A `variable declaration list' in turn
  1004. consists of one or more `variable declarations', separated by
  1005. semicolons." (The latter explanation requires that you understand the
  1006. recursive nature of the definition of `variable_declaration_list'.)
  1007.  
  1008.    Now we can go on and search for `variable_declaration'.
  1009.  
  1010.      variable_declaration:
  1011.          id_list
  1012.            {
  1013.              [...]
  1014.            }
  1015.          enable_caret ':' optional_qualifier_list type_denoter
  1016.            {
  1017.              [...]
  1018.            }
  1019.          absolute_or_value_specification
  1020.            {
  1021.              [...]
  1022.            }
  1023.        ;
  1024.  
  1025.    (The `[...]' are placeholders for some C statements which aren't
  1026. important for understanding GPC's grammar.)
  1027.  
  1028.    From this you can look up that a variable declaration in GNU Pascal
  1029. consists of an "id list", followed by "enable_caret" (whatever that
  1030. means), a colon, an "optional qualifier list", a "type denoter", and an
  1031. "absolute or value specification".  Some of these parts are easy to
  1032. understand, the others you can look up from `parse.y'.  Remember that
  1033. the reserved word `var' precedes all this, and a semicolon follows all
  1034. this.
  1035.  
  1036.    Now you know the procedure how to get the exact grammar of the GNU
  1037. Pascal language from the source.
  1038.  
  1039.    The C statements, not shown above, are in some sense the most
  1040. important part of the bison source, because they are responsible for
  1041. the generation of the intermediate code of the GNU Pascal front-end,
  1042. the so-called _tree nodes_.  For instance, the C code in "type denoter"
  1043. juggles a while with variables of the type `tree', and finally returns
  1044. (assigns to `$$') a so-called _tree list_ which contains the information
  1045. about the type.  The "variable declaration" gets this tree list (as the
  1046. argument `$6') and passes the type information to the C function
  1047. `declare_vars()' (declared in `util.c').  This function
  1048. `declare_vars()' does the real work of compiling a variable declaration.
  1049.  
  1050.    This, the parser, is the place where it becomes Pascal.
  1051.  
  1052. 
  1053. File: gpc.info,  Node: Tree nodes,  Next: Parameter passing,  Prev: Language definition,  Up: Internals
  1054.  
  1055. Tree Nodes
  1056. ==========
  1057.  
  1058.    If you want really to understand how the GNU Pascal language
  1059. front-end works internally and perhaps want to improve the compiler, it
  1060. is important that you understand GPC's internal data structures.
  1061.  
  1062.    The data structure used by the language front-end to hold all
  1063. information about your Pascal program are the so-called "tree nodes".
  1064. (Well, it needn't be Pascal source - tree nodes are language
  1065. independent.)  The tree nodes are kind of objects, connected to each
  1066. other via pointers.  Since the GNU compiler is written in C and was
  1067. created at a time where nobody really thought about object-orientated
  1068. programming languages yet, a lot of effort has been taken to create
  1069. these "objects" in C.
  1070.  
  1071.    Here is an extract from the "object hierarchy".  Omissions are marked
  1072. with "..."; nodes in parentheses are "abstract":  They are never
  1073. instantiated and aren't really defined.  They only appear here to
  1074. clarify the structure of the tree node hierarchy.  The complete list is
  1075. in `../tree.def'; additional information can be found in `../tree.h'.
  1076.  
  1077.      (tree_node)
  1078.      |
  1079.      |--- error_mark  (* enables GPC to continue after first error *)
  1080.      |
  1081.      |--- (identifier)
  1082.      |    |
  1083.      |    |--- identifier_node
  1084.      |    |
  1085.      |    \--- op_identifier
  1086.      |
  1087.      |--- tree_list  (* general-purpose "container object" *)
  1088.      |
  1089.      |--- tree_vec
  1090.      |
  1091.      |--- block
  1092.      |
  1093.      |--- (type)  (* information about types *)
  1094.      |    |
  1095.      |    |--- void_type
  1096.      |    |
  1097.      |    |--- integer_type
  1098.      |   ...
  1099.      |    |
  1100.      |    |--- record_type
  1101.      |    |
  1102.      |    |--- function_type
  1103.      |    |
  1104.      |    \--- lang_type  (* for language-specific extensions *)
  1105.      |
  1106.      |--- integer_cst  (* an integer constant *)
  1107.      |
  1108.      |--- real_cst
  1109.      |
  1110.      |--- string_cst
  1111.      |
  1112.      |--- complex_cst
  1113.      |
  1114.      |--- (declaration)
  1115.      |    |
  1116.      |    |--- function_decl
  1117.      |   ...
  1118.      |    |
  1119.      |    |--- type_decl
  1120.      |    |
  1121.      |    \--- var_decl
  1122.      |
  1123.      |--- (reference)
  1124.      |    |
  1125.      |    |--- component_ref
  1126.      |   ...
  1127.      |    |
  1128.      |    \--- array_ref
  1129.      |
  1130.      |--- constructor
  1131.      |
  1132.      \--- (expression)
  1133.           |
  1134.           |--- modify_expr  (* assignment *)
  1135.           |
  1136.           |--- plus_expr  (* addition *)
  1137.          ...
  1138.           |
  1139.           |--- call_expr  (* procedure/function call *)
  1140.           |
  1141.           |--- goto_expr
  1142.           |
  1143.           \--- loop_expr  (* for all loops *)
  1144.  
  1145.    Most of these tree nodes - struct variables in fact - contain
  1146. pointers to other tree nodes.  A `tree_list' for instance has a
  1147. `tree_value' and a `tree_purpose' slot which can contain arbitrary
  1148. data; a third pointer `tree_chain' points to the next `tree_list' node
  1149. and thus allows us to create linked lists of tree nodes.
  1150.  
  1151.    One example:  When GPC reads the list of identifiers in a variable
  1152. declaration
  1153.  
  1154.      var
  1155.        foo, bar, baz : Integer;
  1156.  
  1157.    the parser creates a chain of `tree_list's whose `tree_value's hold
  1158. `identifier_node's for the identifiers `foo', `bar', and `baz'.  The
  1159. function `declare_vars()' (declared in `util.c') gets this tree list as
  1160. a parameter, does some magic, and finally passes a chain of `var_decl'
  1161. nodes to the back-end.
  1162.  
  1163.    The `var_decl' nodes in turn have a pointer `tree_type' which holds
  1164. a `_type' node - an `integer_type' node in the example above.  Having
  1165. this, GPC can do type-checking when a variable is referenced.
  1166.  
  1167.    For another example, let's look at the following statement:
  1168.  
  1169.      baz := foo + bar;
  1170.  
  1171.    Here the parser creates a `modify_expr' tree node.  This node has two
  1172. pointers, `tree_operand[0]' which holds a representation of `baz', a
  1173. `var_decl' node, and `tree_operand[1]' which holds a representation of
  1174. the sum `foo + bar'.  The sum in turn is represented as a `plus_expr'
  1175. tree node whose `tree_operand[0]' is the `var_decl' node `foo', and
  1176. whose `tree_operand[1]' is the `var_decl' node `bar'.  Passing this
  1177. (the `modify_expr' node) to the back-end results in assembler code for
  1178. the assignment.
  1179.  
  1180.    If you want to have a closer look at these tree nodes, write a line
  1181. `(*$debug-tree="Foobar"*)' into your program with `FooBar' being some
  1182. identifier in your program.  (Note the capitalization of the first
  1183. character in the internal representation.)  This tells GPC to output the
  1184. `identifier_local_value' tree node - the meaning of this identifier -
  1185. to the standard error device in human-readable form.
  1186.  
  1187.    While hacking and debugging GPC, you will also wish to have a look
  1188. at these tree nodes in other cases.  Use the `debug_tree()' function to
  1189. do so.  (In fact `(*$debug-tree="Foobar"*)' does nothing else than to
  1190. `debug_tree()' the `identifier_local_value' of the `Foobar' identifier
  1191. node.)
  1192.  
  1193. 
  1194. File: gpc.info,  Node: Parameter passing,  Next: GPI files,  Prev: Tree nodes,  Up: Internals
  1195.  
  1196. Parameter Passing
  1197. =================
  1198.  
  1199.    GPC supports a lot of funny things in parameter lists:  `protected'
  1200. and `const' parameters, strings with specified or unspecified length,
  1201. conformant arrays, objects as `var' parameters, etc.  All this requires
  1202. sophisticated type-checking; the responsible function is
  1203. `convert_arguments()' in the source file `gpc-typeck.c'.  Every detail
  1204. can be looked up from there.
  1205.  
  1206.    Some short notes about the most interesting cases follow.
  1207.  
  1208. *Conformant arrays:*
  1209.      First, the array bounds are passed (an even number of parameters
  1210.      of an ordinal type), then the address of the array itself.
  1211.  
  1212. *Procedural parameters:*
  1213.      These need special care because a function passed as a parameter
  1214.      can be confused with a call to the function whose result is then
  1215.      passed as a parameter.  See also the functions
  1216.      `maybe_call_function()' and `probably_call_function()' in `util.c'.
  1217.  
  1218. *Chars:*
  1219.      According to ISO-10206 Extended Pascal, formal char parameters
  1220.      accept string values.  GPC does the necessary conversion
  1221.      implicitly.  The empty string produces a space.
  1222.  
  1223. *Strings and schemata:*
  1224.      Value parameter strings and schemata of known size are really
  1225.      passed by value.  Value parameter strings and schemata of unknown
  1226.      size are passed by reference, and GPC creates temporary variable
  1227.      to hold a copy of the string.
  1228.  
  1229. *`const' parameters:*
  1230.      If a constant value is passed to a `const' parameter, GPC assigns
  1231.      the value to a temporary variable whose address is passed.
  1232.  
  1233.      Even if the parameter is passed by value??? - Frank
  1234.  
  1235. *Typeless parameters:*
  1236.      These are denoted by `var foo' or `var foo: Void' and are
  1237.      compatible to C's `void *' parameters; the size of such entities
  1238.      is _not_ passed. Maybe we will change this in the future and pass
  1239.      the size for `var foo' parameters whereas `var foo: Void' will
  1240.      remain compatible to C.  (Same with `const' instead of `var'.)
  1241.  
  1242. *`CString' parameters:*
  1243.      GPC implicitly converts any string value such that the address of
  1244.      the actual string data is passed.  However, GPC did not implicitly
  1245.      append a `Chr (0)' terminator, except for string constants.  It
  1246.      does so now.
  1247.  
  1248. 
  1249. File: gpc.info,  Node: GPI files,  Next: AutoMake,  Prev: Parameter passing,  Up: Internals
  1250.  
  1251. GPI files - GNU Pascal Interfaces
  1252. =================================
  1253.  
  1254.    This section documents the mechanism how GPC transfers information
  1255. from the exporting modules and units to the program, module or unit
  1256. which imports (uses) the information.
  1257.  
  1258.    A GPI file contains a precompiled GNU Pascal interface.
  1259. "Precompiled" means in this context that the interface already has been
  1260. parsed (i.e. the front-end has done its work), but that no assembler
  1261. output has been produced yet.
  1262.  
  1263.    The GPI file format is an implementation-dependent (but not _too_
  1264. implementation-dependent ;-) file format for storing GNU Pascal
  1265. interfaces to be exported - Extended Pascal and PXSC module interfaces
  1266. as well as interface parts of Borland Pascal Units compiled with GNU
  1267. Pascal.
  1268.  
  1269.    To see what information is stored in or loaded from a GPI file, run
  1270. GPC with an additional command-line option `--debug-gpi'.  Then, GPC
  1271. will write a human-readable version of what is being stored/loaded to
  1272. the standard error device.  (See also: *Note Tree nodes::.)
  1273.  
  1274.    While parsing an interface, GPC stores the names of exported objects
  1275. in tree lists - in `gpc-parse.y', the bison (yacc) source of GPC's
  1276. parser, search for `handle_autoexport'.  At the end of the interface,
  1277. everything is stored in one or more GPI files.  This is called in
  1278. `gpc-parse.y' - search for `create_gpi_files'.  (See also: *Note
  1279. Language definition::, for an introduction to `gpc-parse.y')
  1280.  
  1281.    Everything else is done in gpc-module.c.  Here you can find the
  1282. source of `create_gpi_files()' which documents the file format:  First,
  1283. a header of 33 bytes containing the string `GNU Pascal Module/Unit
  1284. Interface\n' is stored, then the name of the primary source file of the
  1285. module as a string, then the name of the exported interface as a tree
  1286. node (see below), after that all exported names in the order as they
  1287. were stored while parsing.
  1288.  
  1289.    The names and the objects (i.e. constants, data types, variables and
  1290. functions) they refer to are internally represented as so-called _tree
  1291. nodes_ as defined in the files `../tree.h' and `../tree.def' from the
  1292. GNU compiler back-end.  (See also: *Note Tree nodes::.)  The names are
  1293. stored as `identifier_node's, their meanings as
  1294. `identifier_global_value's of these nodes.  The main problem when
  1295. storing tree nodes is that they form a complicated tree in memory with
  1296. a lot of circular references making it hard to decide which information
  1297. must be stored and which mustn't.
  1298.  
  1299.    The functions `load_tree()' and `store_tree' load/store a tree node
  1300. with the contents of all its contained pointers in a GPI file.
  1301.  
  1302.    Each tree node has a `tree_code' indicating what kind of information
  1303. it contains.  Each different tree node must be stored in a different
  1304. way.  See the source of `load_tree()' and `store_tree()' for details.
  1305.  
  1306.    Most tree nodes contain pointers to other tree nodes; therefore
  1307. `load_tree()' and `store_tree()' are recursive functions.  The
  1308. `--debug-gpi' debugging informations contains the recursion level in
  1309. parantheses, e.g. `loaded (2):' means that the loaded information was
  1310. requested by a pointer contained in a tree node requested by a pointer
  1311. contained in a tree node representing an exported symbol.
  1312.  
  1313.    Since this recursion can be circular (think of a record containing a
  1314. pointer to a record of the same type), we must resolve references to
  1315. tree nodes which already have been loaded.  For this reason, all nodes
  1316. are recorded in a hash buffer - see `gpi-hash.c'.
  1317.  
  1318.    There are some special tree_nodes (e.g. `integer_type_node' or
  1319. `NULL_TREE') which are used very often.  They have been assigned
  1320. (normally invalid) unique `tree_code's, so they can be stored in a
  1321. single byte.
  1322.  
  1323.    That's it.  Now you should be able to "read" GPI files using GPC's
  1324. `--debug-gpi' option.  If you encounter a case where the loaded
  1325. information differs too much from the stored information, you have
  1326. found a bug - congratulations!  What "too much" means, depends on the
  1327. object being stored in or loaded from the GPI file.  Remind that the
  1328. order things are loaded from a GPI file is the _reversed_ order things
  1329. are stored when considering _different_ recursion levels, but the
  1330. _same_ order when considering ths _same_ recursion level.
  1331.  
  1332.